% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ejamit.R
\name{ejamit}
\alias{ejamit}
\title{Get an EJ analysis (demographic and environmental indicators) in or near a list of locations}
\usage{
ejamit(
  sitepoints,
  radius = 3,
  radius_donut_lower_edge = 0,
  maxradius = 31.07,
  avoidorphans = FALSE,
  quadtree = NULL,
  fips = NULL,
  shapefile = NULL,
  countcols = NULL,
  popmeancols = NULL,
  calculatedcols = NULL,
  subgroups_type = "nh",
  include_ejindexes = TRUE,
  calculate_ratios = TRUE,
  extra_demog = TRUE,
  need_proximityscore = FALSE,
  infer_sitepoints = FALSE,
  need_blockwt = TRUE,
  thresholds = list(80, 80),
  threshnames = list(c(names_ej_pctile, names_ej_state_pctile), c(names_ej_supp_pctile,
    names_ej_supp_state_pctile)),
  threshgroups = list("EJ-US-or-ST", "Supp-US-or-ST"),
  updateProgress = NULL,
  updateProgress_getblocks = NULL,
  in_shiny = FALSE,
  quiet = TRUE,
  parallel = FALSE,
  silentinteractive = FALSE,
  called_by_ejamit = TRUE,
  testing = FALSE,
  showdrinkingwater = TRUE,
  showpctowned = TRUE,
  ...
)
}
\arguments{
\item{sitepoints}{data.table with columns lat, lon giving point locations of sites or facilities around which are circular buffers}

\item{radius}{in miles, defining circular buffer around a site point}

\item{radius_donut_lower_edge}{radius of lower edge of donut ring if analyzing a ring not circle}

\item{maxradius}{miles distance (max distance to check if not even 1 block point is within radius)}

\item{avoidorphans}{logical If TRUE, then where not even 1 BLOCK internal point is within radius of a SITE,
it keeps looking past radius, up to maxradius, to find nearest 1 BLOCK.
What EJScreen does in that case is report NA, right?
So, does EJAM really need to report stats on residents presumed to be within radius,
if no block centroid is within radius?
Best estimate might be to report indicators from nearest block centroid
which is probably almost always the one your site is sitting inside of,
but ideally would adjust total count to be a fraction of blockwt
based on what is area of circular buffer as fraction of area of block it is apparently inside of.
Setting this to TRUE can produce unexpected results, which will not match EJScreen numbers.
Note that if creating a proximity score, by contrast, you
instead want to find nearest 1 SITE if none within radius of this BLOCK.}

\item{quadtree}{(a pointer to the large quadtree object) created using indexblocks() which uses the SearchTree package.
Takes about 2-5 seconds to create this each time it is needed.
It can be automatically created when the package is attached via the .onAttach() function}

\item{fips}{optional FIPS code vector to provide if using FIPS instead of sitepoints to specify places to analyze,
such as a list of US Counties or tracts. Passed to \code{\link[=getblocksnearby_from_fips]{getblocksnearby_from_fips()}}}

\item{shapefile}{optional. A sf shapefile object or path to .zip, .gdb, or folder that has a shapefiles, to analyze polygons.
If in RStudio you want it to interactively prompt you to pick a file,
use shapefile=1 (otherwise it assumes you want to pick a latlon file).}

\item{countcols}{character vector of names of variables to aggregate within a buffer using a sum of counts,
like, for example, the number of people for whom a poverty ratio is known,
the count of which is the exact denominator needed to correctly calculate percent low income.}

\item{popmeancols}{character vector of names of variables to aggregate within a buffer using population weighted mean.}

\item{calculatedcols}{character vector of names of variables to aggregate within a buffer using formulas that have to be specified.}

\item{subgroups_type}{Optional (uses default). Set this to "nh" for non-hispanic race subgroups
as in Non-Hispanic White Alone, nhwa and others in names_d_subgroups_nh;
"alone" for race subgroups like White Alone, wa and others in names_d_subgroups_alone;
"both" for both versions. Possibly another option is "original" or "default"
Alone means single race.}

\item{include_ejindexes}{whether to try to include EJ Indexes (assuming dataset is available) - passed to \code{\link[=doaggregate]{doaggregate()}}}

\item{calculate_ratios}{whether to calculate and return ratio of each indicator to US and State overall averages - passed to \code{\link[=doaggregate]{doaggregate()}}}

\item{extra_demog}{if should include more indicators from v2.2 report on language etc.}

\item{need_proximityscore}{whether to calculate proximity scores}

\item{infer_sitepoints}{set to TRUE to try to infer the lat,lon of each site around which the blocks in sites2blocks were found.
lat,lon of each site will be approximated as average of nearby blocks,
although a more accurate slower way would be to use reported distance of each of 3 of the furthest block points and triangulate}

\item{need_blockwt}{if fips parameter is used, passed to \code{\link[=getblocksnearby_from_fips]{getblocksnearby_from_fips()}}}

\item{thresholds}{list of percentiles like list(80,90) passed to
batch.summarize(), to be
counted to report how many of each set of indicators exceed thresholds
at each site. (see default)}

\item{threshnames}{list of groups of variable names (see default)}

\item{threshgroups}{list of text names of the groups (see default)}

\item{updateProgress}{progress bar function passed to \code{\link[=doaggregate]{doaggregate()}} in shiny app}

\item{updateProgress_getblocks}{progress bar function passed to \code{\link[=getblocksnearby]{getblocksnearby()}} in shiny app}

\item{in_shiny}{if fips parameter is used, passed to \code{\link[=getblocksnearby_from_fips]{getblocksnearby_from_fips()}}}

\item{quiet}{Optional. set to TRUE to avoid message about using \code{\link[=getblocks_diagnostics]{getblocks_diagnostics()}},
which is relevant only if a user saved the output of this function.}

\item{parallel}{whether to use parallel processing in \code{\link[=getblocksnearby]{getblocksnearby()}}, but not implemented yet.}

\item{silentinteractive}{to prevent long output showing in console in RStudio when in interactive mode,
passed to \code{\link[=doaggregate]{doaggregate()}} also. app server sets this to TRUE when calling doaggregate() but
\code{\link[=ejamit]{ejamit()}} default is to set this to FALSE when calling \code{\link[=doaggregate]{doaggregate()}}.}

\item{called_by_ejamit}{Set to TRUE by \code{\link[=ejamit]{ejamit()}} to suppress some outputs even if ejamit(silentinteractive=F)}

\item{testing}{used while testing this function}

\item{...}{passed to \code{\link[=getblocksnearby]{getblocksnearby()}} etc. such as  report_progress_every_n = 0}
}
\value{
A list of tables of results:
\itemize{
\item \strong{results_overall}  a data.table with one row that provides the summary across all sites, the aggregated results for all unique residents.
\item \strong{results_bysite}   results for individual sites (buffers) - a data.table of results,
one row per ejam_uniq_id (i.e., each site analyzed), one column per indicator
\item \strong{results_bybg_people}  results for each block group, to allow for showing the distribution of each
indicator across everyone within each demographic group.
\item \strong{longnames}  descriptive long names for the indicators in the above outputs
\item \strong{count_of_blocks_near_multiple_sites}  additional detail
\item \strong{sitetype} indicates if analysis used latlon, fips, or shp
}
}
\description{
This is the main function in EJAM that runs the analysis.
It does essentially what the web app does, to analyze/summarize near a set of points,
or in a set of polygons from a shapefile, or in a list of Census Units like Counties.
}
\details{
See examples in vignettes/ articles at https://usepa.github.io/EJAM/index.html
}
\examples{

# See examples in vignettes/ articles at https://usepa.github.io/EJAM/index.html

 # All in one step, using functions not shiny app:
 out <- ejamit(testpoints_100_dt, 2)

 \dontrun{
 # Do not specify sitepoints and it will prompt you for a file,
 # if in RStudio in interactive mode!
 out <- ejamit(radius = 3)

  # Specify facilities or sites as points for test data,
  # use 1000 test facility points from the R package
  testsites <- testpoints_1000
  # use facility points in an excel or csv file
   testsites <- latlon_from_anything(
     system.file(paste0("testdata/latlon/",
      "testpoints_10.xlsx"),
    package = "EJAM")
    )
   # head(testsites)
  # use facility points from a random sample of EPA-regulated facilities
  testsites <- testpoints_n(1e3)

  # Specify max distance from sites to look at (residents within X miles of site point)
  radius <- 3.1 # miles

  # Get summaries of all indicators near a set of points
  out <- ejamit(testsites, radius)
  # out <- ejamit("myfile.xlsx", 3.1)

  # out2 <- ejscreenit(testpoints_5)

  # View results overall
  round(t(out$results_overall), 3.1)

  # View plots
   plot_distance_by_group(results_bybg_people = out$results_bybg_people)
   distance_by_group(out$results_bybg_people)

  # View maps
  mapfast(out$results_bysite, radius = 3.1)

  # view results at a single site
  mapfast(out$results_bysite, radius = 3.1)
  # all the raw numbers at one site
  t(out$results_bysite[1, ])

  # if doing just 1st step of ejamit()
  #  get distance between each site and every nearby Census block

  s2b <- testoutput_getblocksnearby_100pts_1miles
  getblocks_diagnostics(s2b)

  testsites <- testpoints_10[2,]
  s2b <- getblocksnearby(testsites, radius = 3.1)
  getblocks_diagnostics(s2b)
  plotblocksnearby(s2b)

  # if doing just 2d step of ejamit()
  #  get summaries of all indicators based on table of distances
  out <- doaggregate(s2b, testsites) # this works now and is simpler

}
}
\seealso{
\code{\link[=getblocksnearby]{getblocksnearby()}} \code{\link[=doaggregate]{doaggregate()}}
}
